SPIM/SAL: SPIM for the Macintosh, Rel 1.0 May 1993
SEE THE END OF THIS FILE FOR IMPORTANT WARRANTY AND COPYRIGHT INFORMATION
Installation
SPIM/SAL requires two auxilliary files, "trap.handler" and "help.text." These files must be located in the same folder as the SPIM/SAL application.
Introduction
SPIM/SAL is a port, to the Apple Macintosh Personal Computer, of SPIM, a MIPS R2000/3000 simulator that was written by James Larus for instructional use at the University of Wisconsin Computer Sciences Departement. Three other versions of SPIM exist: a character-cell terminal version for Unix called "spim", an X windows version for Unix called "xspim", and a version for PC's running WIN32S, also called "SPIM/SAL." These versions are not identical, but they are descended from a common ancestor and offer the same general functionality. See the end of this document for information about obtaining the different versions of SPIM.
A Brief Tutorial
When SPIM/SAL first starts up, it fills the screen with two windows. The top window is the Session Window. This window displays error and status messages to you from the simulator itself. The bottom window is the Console Window, where the user performs I/O with the MIPS program being interpreted.
Pull down the File menu and activate the Open command. You will see a standard Macintosh file selection box. Use this box to choose a MIPS source file. SPIM/SAL will assemble the chosen file and load it into memory. Note that memory is not cleared until you specifically request it, so multiple source files can be loaded on top of each other. To clear the memory, pull down the File menu, drag down to the Clear command,
then drag to the All command on the submenu.
If there are errors in your source file, SPIM/SAL's assembler will write error messages to the Session window. After about fifty errors have been reported, SPIM/SAL will simply say "Too many errors" and give up trying to assemble your source file.
Once your program has successfully loaded, you can view its text segments in the Text Window and its data segments in the Data Window. Both of these windows are made to appear by selecting them from the Windows menu. This menu also has commands for tiling your windows -- giving each open window an equal amount of screen space and making all of them visible.
To run your program, choose the Run command from the Execute menu. A window will pop up asking you for a start address. By default, this address is the value of your program's __start label. You can type in a different address if you want.
Reference Section
The following paragraphs detail the operation of each menu command and dialog box you will encounter.
Loading Files
Load assembly files into SPIM/SAL by selecting "Load" from the "File" menu, which will bring up the standard Macintosh file selection dialog box. SPIM/SAL assembly files ordinarily end with a ".s" suffix, but you can read any file of type TEXT. Files are parsed as they are loaded. Any errors are written to the Session window.
Clearing State
Clear SPIM/SAL's machine state by selecting "Clear" from the "File" menu. You may clear only registers, only the Console window, or all of registers, memory, and the Console window by making a selection from the Clear menu.
Exiting SPIM/SAL
Exit SPIM/SAL by selecting "Quit" from the "File" menu.
Executing Programs
To execute a program, select "Run" from the "Execute" menu. A dialog box will be presented that will allow you to select the starting address. If the current PC is in a text segment, then it is the default starting address. Otherwise, if the global __start is defined, then the default starting address is its value. Otherwise, the default is 0x04000000, the base of the text segment. After pressing "Execute", the program will begin running. Another dialog box appears that gives you the opportunity to interrupt execution by pressing a button.
Stepping Programs
To step a program, select "Step" from the "Execute" menu. A dialog box will be presented that will allow you to select the number of steps to take. The starting address is determined by the same rules for the default address in the Run dialog; it will be the current PC, __start, or the base of the text segment, as apropriate. This dialog box remains active until you close it; this allows you to step the program repeatedly with a minimum of interaction. When stepping, instructions are echoed to the Session window as they are executed.
Managing Breakpoints
Set, delete, and list breakpoints by selecting "Breakpoints" from the "Execute" menu. A dialog box will be presented that will allow you to select an operation and, for setting and deleting breakpoint, a target address. It is an error to select an address at which there is no instruction; this error generates a message in the Session window.
When a breakpoint is encountered during program execution, execution halts and a dialog box is presented that allows you the choice of continuing or aborting execution.
Printing Data
To print data, select "Print" from the "Data" menu. A dialog box will be presented that will allow you to select a range of addresses. After pressing "Memory", the information will be presented in the Session window. By pressing "Globals", you can see a list of all currently defined global symbols, also written to the Session window.
Setting Data
To set data values, select "Set" from the "Data" menu. A dialog box will be presented that will allow you to specify and address and a value to set it to. You can set the registers by giving a register name as the address.
SPIM/SAL Windows
There are five windows, which you make visible by choosing them from the "Windows" menu. The Session window displays messages from SPIM/SAL itself. The Console window is where you interact with a running program's I/O system calls. The Register window displays the machine's hardware state. The Text and Data windows display the contents of memory.
The windows behave in the usual Macintosh fashion as to scrolling and resizing. By choosing "Close All" from the Windows menu, you can close all five windows. The two "Tile" commands give each open window an equal share of the screen.
Selecting Options
Select "Options" from the menu to set bare or quiet mode.
Important Legalese:
NO WARRANTY
BECAUSE THIS PROGRAM IS LICENSED FREE OF CHARGE THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. THE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH THE USER. SHOULD THE PROGRAM PROVE INEFFECTIVE, THE USER ASSUMES THE COST OF ALL NECESSARY SERVICING REPAIR OR CORRECTION.
IN NO EVENT, UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED IN ACCORDANCE WITH THE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THE USER OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
This Program is free software; the licensee may redistribute it and/or modify it under the terms of the GNU General Public License (version 1 or at your option, any later version) as published by the Free Software Foundation. See the GNU General Public License, for further details.
YOU MAY OBTAIN A COMPLETE MACHINE READABLE COPY OF THE SOURCE CODE CORRESPONDING TO THIS PROGRAM BY WRITING TO: Marketing Department, Saunders College Publishing, 620 Chestnut Street, Public Ledger Building, Suite 560, Philadelphia PA 19106, (215) 238-8423. For Users of A Programmer's View of Computer Architecture by Goodman and Miller write to the above Saunders College Address. For Users of Computer Organization and Design by Hennessy and Patterson write to Morgan Kaufmann Publishers, 2929 Campus Drive, Suite 260, San Mateo CA 94403, (415) 578-9911.
SUCH SOURCE CODE PROGRAMMING WILL ALSO BE SUBJECT TO THE LICENSE REQUIREMENTS PERTAINING TO THE MACHINE READABLE VERSION OF THE PROGRAM.
